android.ndk.trace source code

1 /*
2  * Copyright (C) 2015 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /**
18  * @addtogroup Tracing
19  * @{
20  */
21 
22 /**
23  * @file trace.h
24  * @brief Writes trace events to the system trace buffer.
25  *
26  * These trace events can be collected and visualized using the Systrace tool.
27  * For information about using the Systrace tool, read <a href="https://developer.android.com/studio/profile/systrace.html">Analyzing UI Performance with Systrace</a>.
28  *
29  * Available since API level 23.
30  */
31 
32 module android.ndk.trace;
33 
34 import arsd.jni;
35 import android.ndk;
36 
37 extern (C):
38 nothrow:
39 @nogc:
40 
41 /**
42  * Returns true if tracing is enabled. Use this to avoid expensive computation only necessary
43  * when tracing is enabled.
44  *
45  * Available since API level 23.
46  */
47 bool ATrace_isEnabled ();
48 
49 /**
50  * Writes a tracing message to indicate that the given section of code has begun. This call must be
51  * followed by a corresponding call to {@link ATrace_endSection} on the same thread.
52  *
53  * Note: At this time the vertical bar character '|' and newline character '\\n' are used internally
54  * by the tracing mechanism. If \p sectionName contains these characters they will be replaced with a
55  * space character in the trace.
56  *
57  * Available since API level 23.
58  */
59 void ATrace_beginSection (const(char)* sectionName);
60 
61 /**
62  * Writes a tracing message to indicate that a given section of code has ended. This call must be
63  * preceeded by a corresponding call to {@link ATrace_beginSection} on the same thread. Calling this method
64  * will mark the end of the most recently begun section of code, so care must be taken to ensure
65  * that {@link ATrace_beginSection}/{@link ATrace_endSection} pairs are properly nested and called from the same thread.
66  *
67  * Available since API level 23.
68  */
69 void ATrace_endSection ();
70 
71 /* __ANDROID_API__ >= 23 */
72 
73 /**
74  * Writes a trace message to indicate that a given section of code has
75  * begun. Must be followed by a call to {@link ATrace_endAsyncSection} with the same
76  * methodName and cookie. Unlike {@link ATrace_beginSection} and {@link ATrace_endSection},
77  * asynchronous events do not need to be nested. The name and cookie used to
78  * begin an event must be used to end it.
79  *
80  * \param sectionName The method name to appear in the trace.
81  * \param cookie Unique identifier for distinguishing simultaneous events
82  */
83 void ATrace_beginAsyncSection (const(char)* sectionName, int cookie);
84 
85 /**
86  * Writes a trace message to indicate that the current method has ended.
87  * Must be called exactly once for each call to {@link ATrace_beginAsyncSection}
88  * using the same name and cookie.
89  *
90  * \param methodName The method name to appear in the trace.
91  * \param cookie Unique identifier for distinguishing simultaneous events
92  */
93 void ATrace_endAsyncSection (const(char)* sectionName, int cookie);
94 
95 /**
96  * Writes trace message to indicate the value of a given counter.
97  *
98  * \param counterName The counter name to appear in the trace.
99  * \param counterValue The counter value.
100  */
101 void ATrace_setCounter (const(char)* counterName, long counterValue);
102 
103 /* __ANDROID_API__ >= 29 */
104 
105 // ANDROID_NATIVE_TRACE_H
106 
107 /** @} */